﻿////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// <copyright>Copyright 2008-2011 Andreas Huber Doenni</copyright>
// Distributed under the Microsoft Public License (Ms-PL).
// See accompanying file License.txt or copy at http://mews.codeplex.com/license.
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

namespace Mews.Net
{
    using System.IO;

    /// <summary>Represents the method that creates a <see cref="CommandStream"/> object, through which a stage command
    /// can be written.</summary>
    /// <param name="isMultiline">The value <c>true</c> to indicate a multi-line stage command; <c>false</c> to
    /// indicate a single-line stage command, see <see cref="CommandStream.Write">CommandStream.Write</see> and
    /// <see cref="CommandStream.Dispose">CommandStream.Dispose</see> for more information.</param>
    /// <returns>A <see cref="CommandStream"/> object.</returns>
    /// <remarks>
    /// <para>Calling an instance of <see cref="CreateCommandStreamCallback"/> or
    /// <see cref="CreateResponseStreamCallback"/> automatically calls <see cref="Stream.Dispose()"/> on the previously
    /// created stream (<see cref="CommandStream"/> or <see cref="ResponseStream"/>).</para>
    /// <para>Whether a <b>standard</b> stage command is multi-line or not usually depends on the server response to the
    /// previous stage of the same command. So, the first stage is never multi-line for standard commands and they
    /// therefore all pass <c>false</c>. The ability for multi-line first stages is only provided for the sake of
    /// completeness and of course experimental purposes.</para>
    /// <para>A command <b>usually</b> does not handle exceptions thrown from this callback, but simply lets them
    /// propagate to the code issuing the command.</para>
    /// <para>See <see cref="CommandStream"/> for more information.</para>
    /// </remarks>
    public delegate CommandStream CreateCommandStreamCallback(bool isMultiline);
}
